Skip to main content

Further Examples

These examples will help users consolidate their understanding of API requests to the Data Hub. Refer to the other API Guides before proceeding

Example 1 - Unemployment Indicator​

Follow the steps below to send an API request for the Unemployment Rate in British Columbia in March-2018.

Indicator​

The Unemployment Rate has an ID in the Data Hub of 6, therefore:

indicator=6

Time stamp​

Select the date March-2018, noting the day of the month is arbitary as the data is monthly:

start=20180306&end=20180306

Geography​

As the default geography is Canada, not British Columbia, the API request must specify this point. Were an API request to be made without further steps, the unemployment for Canada on the given date would be returned.

Request that the level of aggregation returned be at a provincial and territorial level by adding a further parameter to the endpoint and query string:

geo=provinces_territories

Now that provinces and territories aggregation has been specificed, a query in this current state would return records for each one. A filter is needed to return only British Columbia.

In the body of the API request add the following filter:

{"province_territory":["BC"]}

Request & response overview​

In combining the query strings and filters as above, the API request for this example will resemble the following in CURL format:

curl --location --request POST 'https://lmic-datahub-prod-gw-d6ow9n6v.uc.gateway.dev/lmi?indicator=6&geo=provinces_territories&start=20180306&end=20180306' \
--header 'x-api-key: API_KEY_HERE' \
--header 'Content-Type: application/json' \
--data-raw '{"province_territory":["BC"]}'

' The API response:

{
    "data": [
        {
            "source": "LFS-14100017; LFS-14100287",
            "as_of_date": "2022-03-01",
            "ref_date": "2018-03-01",
            "data_frequency": "monthly",
            "country": "Canada",
            "provinces_territories": "BC",
            "cma_en": null,
            "economic_regions_en": null,
            "sex_en": "Both sexes",
            "age_en": "15 years and over",
            "noc_level": null,
            "noc_code": null,
            "noc_title_en": null,
            "naics_level": null,
            "naics_code": null,
            "naics_title_en": null,
            "adjustment_en": "unadjusted",
            "indicator_name_en": "Unemployment rate",
            "indicator_value": 0.048
        }
    ],
    "meta": {
        "current_page": 1,
        "total_pages": 1,
        "per_page": 1000,
        "total_rows": 1
    }
}

Indicator value in data highlights that the Unemployment Rate of men in British Columbia on 2018-03-06 is 4.8%. Note that the Unemployment Rate indicator is reported monthly, therefore any date within March-2018 would return the same indicator value.

Example 2 - Job Postings​

Follow the steps below to send a request for the Job Postings Count in the 'Montréal' Census area in 2021 with the NOC 'Professional occupations in natural and applied sciences'.

Indicator​

The Job Postings Counts Indicator has an ID in the Data Hub of 14 making the query string:

indicator=14

Time stamp​

To select the dates which fall within 2022 the Start and End parameters are used with the format YYYYMMDD, giving the endpoint:

start=20210101&end=20211231

Geography​

Filter for the Montréal Census area.

Firstly, request that the level of aggregation returned be at a census area level by adding a further parameter to the endpoint and query string:

geo=census_division

Secondly, in the body of the API request add the following filter to return only the Montréal census area:

{"cma":["Montréal"]}

Frequency​

Job Postings Indicators' have a monthly default aggregation. Therefore, the API request in its state above would return 12 records, one for each month in 2021. Use the the query string as follows to aggregate the API response annually:

freq=annual

NOC​

'Professional occupations in natural and applied sciences' has NOC ID of 2. Edit the JSON body to filter for only NOC 2:

"noc": "2"

Request & Response Overview​

In combining the query strings and filters as above, the API request for this example will resemble the following in CURL format:

curl --location --request POST 'https://lmic-datahub-prod-gw-d6ow9n6v.uc.gateway.dev/lmi?indicator=14&geo=census_division&start=20210101&end=20211231&freq=annual&noc_level=1' \
--header 'x-api-key: API_KEY' \
--header 'Content-Type: application/json' \
--data-raw '{"census_division":["Montréal"],"noc": "2"}

The API response:

    {
        "data": [
            {
                "source": "Vicinity Jobs",
                "ref_date": "2021-12-31",
                "data_frequency": "annual",
                "noc_code": "2",
                "noc_level": 1,
                "noc_title_en": "Natural and applied sciences and related occupations",
                "country": "Canada",
                "provinces_territories": "QC",
                "economic_regions_en": "Montréal",
                "census_division": "Montréal",
                "location": null,
                "indicator_name_en": "Job postings count",
                "indicator_value": 14545
            }
        ],
        "meta": {
            "current_page": 1,
            "total_pages": 1,
            "per_page": 1000,
            "total_rows": 1
        }
    }

Example 3 - Work Requirements​

Follow the steps below to send a request for the Work Requirements Share for 'Financial auditors and accountants' in the 'Toronto' economic region in 2021.

Indicator​

The Work Requirements Share Indicator has an ID in the Data Hub of 18, making the query string:

indicator=18

Frequency​

Job Postings Indicators' have a monthly default aggregation. Therefore, the API request in its state above would return 12 records, one for each month in 2021. Use the the query string as follows to aggregate the API response annually:

freq=annual

Time stamp​

Selecting dates for this indicator can be error prone. The data source, Vicinity Jobs provides monthly data, and the API will return data aggregated by month by default. In this case, where a year is required, the user must include in the start and end parameters, the month of Jan-2021 and Dec-2021 respectively. If a date inside those months is requested, the API will return a blank response as less than 1 year of data is requested. With these points in mind, the 2021 string query could resemble:

start=20210101&end=20211201

Geography​

Filter for the 'Toronto' economic region.

Firstly, request that the level of aggregation returned be at a economic region level by adding a further parameter to the endpoint and query string:

geo=economic_regions

Secondly, in the body of the API request add the following filter to return only the 'Montréal' Census area:

{"economic_region":["Toronto"]}

NOC​

In a similar fashion to the Geography filter, firstly, specify the query string:

noc_level=4

By selecting NOC level 4, the filter can specify the detailed noc for 'Financial auditors and accountants'.

Secondly, in the body of the API request add the following filter to return only the noc of 1111:

"noc":["1111"]

Request & response overview​

In combining the query strings and filters as above, the API request for this example will resemble the following in CURL format:

curl --location --request POST 'https://lmic-datahub-prod-gw-d6ow9n6v.uc.gateway.dev/lmi?indicator=18&geo=economic_regions&start=20200101&end=20201201&freq=annual&noc_level=4' \
--header 'x-api-key: API_KEY_HERE' \
--header 'Content-Type: application/json' \
--data-raw '{"noc":["1111"],"economic_region":["Toronto"]}

The API response (first header only):

{
    "data": [
        {
            "source": "Vicinity Jobs",
            "ref_date": "2020-12-31",
            "data_frequency": "annual",
            "group_en": "Knowledge",
            "work_requirement_en": "Accounting",
            "education_level_en": "Occupations usually require university education",
            "noc_code": "1111",
            "noc_level": 4,
            "noc_title_en": "Financial auditors and accountants",
            "country": "Canada",
            "provinces_territories": "ON",
            "economic_regions_en": "Toronto",
            "census_division": null,
            "location": null,
            "indicator_name_en": "Share of job postings",
            "indicator_value": 0.687
        },